Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:SliderCell;,SliderCell

Inherits From:	ActionCell : Cell : Object

Declared In:	appkit/SliderCell.h

Class Description

SliderCell is a type of Cell used to assist the Slider class, and to build Matrices of sliders.  See the Slider class specification for an overview of how SliderCells work.

Instance Variables

double value;

double maxValue;

double minValue;

NXRect trackRect;

value 	The current value of the SliderCell.

maxValue 	The maximum value of the SliderCell.

minValue 	The minimum value of the SliderCell.

trackRect 	The tracking area of the SliderCell, inside the bezel.

Method Types

Initializing a new SliderCell	- init

Determining component sizes	- calcCellSize:inRect: 
- getKnobRect:flipped:

Setting value limits	- setMinValue: 
- minValue
- setMaxValue: 
- maxValue

Setting values	- setDoubleValue: 
- doubleValue
- setFloatValue: 
- floatValue
- setIntValue: 
- intValue
- setStringValue: 
- stringValue

Modifying a SliderCell's appearance
- setKnobThickness:
- knobThickness
- setImage:
- image
- setTitle:
- setTitleNoCopy:
- title
- setTitleCell:
- titleCell
- setTitleFont:
- titleFont
- setTitleColor:
- titleColor
- setTitleGray:
- titleGray
- isOpaque
- isVertical

Displaying the SliderCell	- drawSelf:inView:
- drawInside:inView: 
- drawBarInside:flipped:
- drawKnob
- drawKnob: 

Modifying behavior	- setEnabled:
- setContinuous:
- isContinuous
- setAltIncrementValue:
- altIncrementValue

Tracking the mouse	+ prefersTrackingUntilMouseUp
- trackMouse:inRect:ofView:
- startTrackingAt:inView: 
- continueTracking:at:inView: 
- stopTracking:at:inView:mouseIsUp: 

Archiving	- read: 
- write:
- awake

Class Methods

NS_DEV_DOCFOR:objc_method:[SliderCell-prefersTrackingUntilMouseUp];,prefersTrackingUntilMouseUp

+ (BOOL)prefersTrackingUntilMouseUp

Returns YES so a SliderCell can track mouse-dragged and mouse-up events even if they occur outside its frame.  This ensures that a SliderCell in a Matrix doesn't stop responding to user input (and its neighbor start) just because the knob isn't dragged in a perfectly straight line. Override this method to allow a SliderCell to stop tracking if the mouse moves outside its frame while tracking.

Instance Methods

NS_DEV_DOCFOR:objc_method:[SliderCell-altIncrementValue];,altIncrementValue

- (double)altIncrementValue

Returns the amount that the SliderCell will alter its value when the user drags the knob one pixel with the Alternate key held down.  If the Alternate-dragging feature isn't enabled, this method returns -1.0.

See also:  - setAltIncrementValue:

NS_DEV_DOCFOR:objc_method:[SliderCell-awake];,awake

- awake

Retrieves the system images used to draw SliderCell knobs, and returns self.  This message is sent from the read: method; you never send it yourself.

See also:  - read:

NS_DEV_DOCFOR:objc_method:[SliderCell-calcCellSize:inRect:];,calcCellSize:inRect:

- calcCellSize:(NXSize *)theSize inRect:(const NXRect *)aRect

Returns self, and by reference in theSize the minimum width and height needed to draw the SliderCell in aRect.  If aRect too small to fit the knob and bezel, the width and height of theSize are set to 0.0.

If the SliderCell hasn't had its tracking rectangle set, this method will determine from aRect whether the SliderCell should be vertical or horizontal, and will set a vertical SliderCell's height to aRect->size.height, a horizontal SliderCell's width to aRect->size.width, and the other dimension of either type to the minimum SliderCell breadth.

If you draw your own knob on the SliderCell and that knob is not the same size as a standard SliderCell knob, or if you draw the SliderCell itself differently, you should override this method to take your knob's dimensions into account.  You must also override getKnobRect:flipped: and drawKnob:.

Note:  It's usually wrong to invoke the inherited calcCellSize: method.  Instead, calcCellSize:inRect: should be used with a valid rectangle for displaying the SliderCell.

See also:  - getKnobRect:flipped:, - drawKnob:

NS_DEV_DOCFOR:objc_method:[SliderCell-continueTracking:at:inView:];,continueTracking:at:inView:

- (BOOL)continueTracking:(const NXPoint *)lastPoint
at:(const NXPoint *)currentPoint
inView:controlView

Continues tracking by moving the knob to currentPoint.  Always returns YES.  Invokes getKnobRect:flipped: to get the current location of the knob and drawKnob to draw the knob at the new position based on currentPoint.

Override this method if you want to change the way positioning is done.

See also:  - trackMouse:inRect:ofView:, - startTrackingAt:inView:, - stopTracking:at:inView:mouseIsUp:

NS_DEV_DOCFOR:objc_method:[SliderCell-doubleValue];,doubleValue

- (double)doubleValue

Returns the value of the SliderCell as a double-precision floating point number.

See also:  - setDoubleValue:, - floatValue, - intValue, - stringValue

NS_DEV_DOCFOR:objc_method:[SliderCell-drawBarInside:flipped:];,drawBarInside:flipped:

- drawBarInside:(const NXRect *)cellFrame flipped:(BOOL)flipped

Draws the SliderCell's background bar, but not the bezel around it or the knob.  flipped indicates whether the View's coordinate system is flipped or not.  Returns self.

Override this method if you want to draw your own slider bar.  Note, however, that the setImage: method allows you to conveniently customize the appearance of the SliderCell's background.

See also:  - drawInside:inView:, - drawSelf:inView:, - isFlipped (View), - setImage:, - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[SliderCell-drawInside:inView:];,drawInside:inView:

- drawInside:(const NXRect *)cellFrame inView:controlView

Draws the SliderCell's background bar and knob, along with the background title, but not the bezel.  The PostScript focus must be locked on controlView when this message is sent.  Returns self.

See also:  - drawBarInside:flipped:, - drawKnob, - drawSelf:inView:, - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[SliderCell-drawKnob];,drawKnob

- drawKnob

Calculates the rectangle in which the knob should be drawn and invokes drawKnob: to actually draw the knob.  The PostScript focus must be locked on the SliderCell's View when this message is sent.  You never override this method; override drawKnob: instead.

See also:  - drawKnob:, - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[SliderCell-drawKnob:];,drawKnob:

- drawKnob:(const NXRect*)knobRect

Draws the knob in knobRect.  The PostScript focus must be locked on the SliderCell's View when this message is sent.

Override this method and getKnobRect:flipped: if you want to draw your own knob.  You should also override calcCellSize:inRect: if your knob is of a different size from the standard SliderCell knob.

See also:  - drawKnob, - getKnobRect:flipped:, - calcCellSize:inRect:, - isVertical, - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[SliderCell-drawSelf:inView:];,drawSelf:inView:

- drawSelf:(const NXRect *)cellFrame inView:controlView

Draws the SliderCell background bar (including the bezel) and knob.  The knob is drawn at a position which reflects the current value of the SliderCell.  This method doesn't invoke drawInside:inView:.  The PostScript focus must be locked on controlView when this message is sent.  Returns self.

This method invokes calcCellSize:inRect: and centers the resulting sized rectangle in cellFrame, draws the bezel, fills the bar with NX_LTGRAY if the cell is disabled, and 0.5 gray if not, then invokes drawKnob.

If, for example, you want a SliderCell that could be any size, you simply have calcCellSize:inRect: return whatever size you deem appropriate, override getKnobRect:flipped: to return the correct rectangle to draw the knob in, and drawKnob: so that an appropriate knob is drawn.

See also:   - drawBarInside:flipped:, - drawKnob, - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[SliderCell-floatValue];,floatValue

- (float)floatValue

Returns the value of the SliderCell as a single-precision floating point number.

See also:  - setFloatValue:, - doubleValue, - intValue, - stringValue

NS_DEV_DOCFOR:objc_method:[SliderCell-getKnobRect:flipped:];,getKnobRect:flipped:

- getKnobRect:(NXRect*)knobRect flipped:(BOOL)flipped

Returns self, and by reference in knobRect the rectangle into which the knob will be drawn.  This rectangle is determined from the SliderCell's value in relation to its tracking rectangle and its minimum and maximum values.  flipped indicates whether the SliderCell's View has a flipped coordinate system.

Override this method and drawKnob: if you want to draw your own knob.  You should also override calcCellSize:inRect: if your knob is of a different size from the standard SliderCell knob (and be careful of setting the knob's width).  Remember to take into account the flipping of the View in vertical SliderCells; otherwise, your knob might appear the correct distance from the wrong end.

See also:  - drawKnob:, - calcCellSize:inRect:, - isVertical, - isFlipped (View)

NS_DEV_DOCFOR:objc_method:[SliderCell-image];,image

- image

Returns the NXImage that the SliderCell displays as its background.

See also:  - setImage:

NS_DEV_DOCFOR:objc_method:[SliderCell-init];,init

- init

Initializes and returns the receiver, a new instance of SliderCell.  Its value is set to 0.0, minimum value to 0.0, and maximum value to 1.0.  New SliderCells are continuous by default.

This method is the designated initializer for SliderCell; override it if you create a subclass of SliderCell that performs its own initialization.  You shouldn't use Cell's designated initializers, initIconCell: or initTextCell:, to initialize a SliderCell.

See also:  - setMinValue:, - setMaxValue:, - setFloatValue:, - setContinuous:

NS_DEV_DOCFOR:objc_method:[SliderCell-intValue];,intValue

- (int)intValue

Returns the value of the SliderCell as an integer.

See also:  - setIntValue:, - doubleValue, - floatValue, - stringValue

NS_DEV_DOCFOR:objc_method:[SliderCell-isContinuous];,isContinuous

- (BOOL)isContinuous

Returns YES if the action is sent to the target continuously as mouse-dragged events occur while tracking, or on a mouse-up event; NO if the action is sent only on a mouse-up event.

See also:  - setContinuous:

NS_DEV_DOCFOR:objc_method:[SliderCell-isOpaque];,isOpaque

- (BOOL)isOpaque

Returns YES, since a SliderCell always draw over every pixel in its frame.

See also:  - isOpaque (Cell)

NS_DEV_DOCFOR:objc_method:[SliderCell-isVertical];,isVertical

- (int)isVertical

Returns 1 if the SliderCell is vertical, 0 if it's horizontal, and -1 if the orientation can't be determined (because the SliderCell hasn't been drawn in a View, for example).  A SliderCell is vertical if its height is greater than its width.

NS_DEV_DOCFOR:objc_method:[SliderCell-knobThickness];,knobThickness

- (NXCoord)knobThickness

Returns the thickness of the SliderCell's knob (that is, its extent along the bar's length) in the SliderCell's coordinate system.

See also:  - setKnobThickness:

NS_DEV_DOCFOR:objc_method:[SliderCell-maxValue];,maxValue

- (double)maxValue

Returns the maximum value of the SliderCell.

See also:  - setMaxValue:, - minValue

NS_DEV_DOCFOR:objc_method:[SliderCell-minValue];,minValue

- (double)minValue

Returns the minimum value of the SliderCell.

See also:  - setMinValue:, - maxValue

NS_DEV_DOCFOR:objc_method:[SliderCell-read:];,read:

- read:(NXTypedStream *)stream

Reads the SliderCell from the typed stream stream.  Returns self.

See also:  - write:, - awake

NS_DEV_DOCFOR:objc_method:[SliderCell-setAltIncrementValue:];,setAltIncrementValue:

- setAltIncrementValue:(double)incValue

Sets the amount that the SliderCell will alter its value when the user drags the knob one pixel with the Alternate key held down.  incValue should be greater than 0.0, and less than the SliderCell's maximum value; it can also be -1, in which case this feature is disabled.  Normally, you'll want to use this method with incValue less than 1.0, so the knob will move more slowly than the mouse.

See also:  - altIncrementValue, - maxValue

NS_DEV_DOCFOR:objc_method:[SliderCell-setContinuous:];,setContinuous:

- setContinuous:(BOOL)flag

If flag is YES, the SliderCell will send its action to its target continuously as mouse-dragged events occur while tracking, or on a mouse-up event.  If NO, the SliderCell will send its action only on a mouse-up event.  The default is YES.  Returns self.

See also:  - isContinuous

NS_DEV_DOCFOR:objc_method:[SliderCell-setDoubleValue:];,setDoubleValue:

- setDoubleValue:(double)aDouble

Sets the value of the SliderCell to aDouble.  Updates the SliderCell knob position to reflect the new value and returns self.

See also:  - doubleValue, - setFloatValue:, - setIntValue:, - setStringValue:

NS_DEV_DOCFOR:objc_method:[SliderCell-setEnabled:];,setEnabled:

- setEnabled:(BOOL)flag

If flag is YES, the SliderCell will become enabled; if NO, the SliderCell will become disabled.  A disabled SliderCell draws its non-image background in light gray.  An enabled SliderCell draws its non-image background in 50% gray.

See also:  - isEnabled (ActionCell)

NS_DEV_DOCFOR:objc_method:[SliderCell-setFloatValue:];,setFloatValue:

- setFloatValue:(float)aFloat

Sets the value of the SliderCell to aFloat.  Updates the SliderCell knob position to reflect the new value and returns self.

See also:  - floatValue, - setDoubleValue:, - setIntValue:, - setStringValue:

NS_DEV_DOCFOR:objc_method:[SliderCell-setImage:];,setImage:

- setImage:image

Sets the NXImage used as the SliderCell's background.  This method doesn't scale the NXImage.  Returns self.

See also:  - image

NS_DEV_DOCFOR:objc_method:[SliderCell-setIntValue:];,setIntValue:

- setIntValue:(int)anInt

Sets the value of the SliderCell to anInt.  Updates the SliderCell knob position to reflect the new value and returns self.

See also:  - intValue, - setDoubleValue:, - setFloatValue:, - setStringValue:

NS_DEV_DOCFOR:objc_method:[SliderCell-setKnobThickness:];,setKnobThickness:

- setKnobThickness:(NXCoord)aFloat

Sets the thickness of the SliderCell's knob (that is, its extent along the bar's length) in its own coordinate system.  aFloat must be greater than 0.0, and shouldn't be greater than the Slider's length.  If the knob thickness changes, the SliderCell's inside is redrawn.  Returns self.

See also:  - knobThickness

NS_DEV_DOCFOR:objc_method:[SliderCell-setMaxValue:];,setMaxValue:

- setMaxValue:(double)aDouble

Sets the maximum value of the SliderCell to aDouble and returns self.  If the maximum value changes, the SliderCell's inside is redrawn to reposition the knob relative to the new maximum.

See also:  - maxValue, - setMinValue:

NS_DEV_DOCFOR:objc_method:[SliderCell-setMinValue:];,setMinValue:

- setMinValue:(double)aDouble

Sets the minimum value of the SliderCell to aDouble and returns self.  If the minimum value changes, the SliderCell's inside is redrawn to reposition the knob relative to the new minimum.

See also:  - minValue, - setMaxValue:

NS_DEV_DOCFOR:objc_method:[SliderCell-setStringValue:];,setStringValue:

- setStringValue:(const char *)aString

Parses aString for a floating point value.  If a floating point value can be found, then the SliderCell value is set and the knob position is updated to reflect the new value; otherwise, does nothing.  Returns self.

Note:  SliderCell doesn't override the setStringValueNoCopy: or setStringValueNoCopy:shouldFree: methods; you shouldn't use those methods with a SliderCell.

See also:  - stringValue, - setDoubleValue:, - setFloatValue:, - setIntValue:

NS_DEV_DOCFOR:objc_method:[SliderCell-setTitle:];,setTitle:

- setTitle:(const char *)aString

Sets the title drawn over the SliderCell's background to aString.  Returns self.

See also:  - setTitleNoCopy:, - title

NS_DEV_DOCFOR:objc_method:[SliderCell-setTitleCell:];,setTitleCell:

- setTitleCell:aCell

Sets the Cell used to draw the SliderCell's background title.  aCell should be an instance of TextFieldCell (or of a subclass).  Doesn't redraw the SliderCell; further, a setTitle: message is required to display a title, even if aCell already has a string value.  Returns the old Cell.

See also:  - titleCell, - setTitle:

NS_DEV_DOCFOR:objc_method:[SliderCell-setTitleColor:];,setTitleColor:

- setTitleColor:(NXColor)color

Sets the color used to draw the SliderCell's background title, redraws the SliderCell's inside, and returns self.  The default is to draw in a gray level of 0.0 (NX_BLACK).

See also:  - titleColor, - setTitleGray:

NS_DEV_DOCFOR:objc_method:[SliderCell-setTitleFont:];,setTitleFont:

- setTitleFont:fontObject

Sets the Font used to draw the SliderCell's background title and redraws the SliderCell's inside.  The default font is the default system font as set by the user (with the Preferences application), and its size is 12.0 point.  Returns self.

See also:  - titleFont

NS_DEV_DOCFOR:objc_method:[SliderCell-setTitleGray:];,setTitleGray:

- setTitleGray:(float)aFloat

Sets the gray value used to draw the SliderCell's background title, redraws the SliderCell's inside, and returns self.  The default gray level is 0.0 (NX_BLACK).

See also:  - titleGray, - setTitleColor:

NS_DEV_DOCFOR:objc_method:[SliderCell-setTitleNoCopy:];,setTitleNoCopy:

- setTitleNoCopy:(const char *)aString

Sets the title drawn over the SliderCell's background to aString, but doesn't copy the string.  Returns self.

See also:  - setTitle:, - title

NS_DEV_DOCFOR:objc_method:[SliderCell-startTrackingAt:inView:];,startTrackingAt:inView:

- (BOOL)startTrackingAt:(const NXPoint *)startPoint inView:controlView

Begins a tracking session by moving the knob to startPoint.  Always returns YES.

See also:  - trackMouse:inRect:ofView:, - continueTracking:at:inView:, - stopTracking:at:inView:mouseIsUp:

NS_DEV_DOCFOR:objc_method:[SliderCell-stopTracking:at:inView:mouseIsUp:];,stopTracking:at:inView:mouseIsUp:

- stopTracking:(const NXPoint *)lastPoint
at:(const NXPoint *)stopPoint
inView:controlView
mouseIsUp:(BOOL)flag

Ends tracking by moving the knob to stopPoint.  Returns self.

See also:  - trackMouse:inRect:ofView:, - startTrackingAt:inView:, - continueTracking:at:inView:

NS_DEV_DOCFOR:objc_method:[SliderCell-stringValue];,stringValue

- (const char *)stringValue

Returns a string representing the value of the SliderCell.  The floating point format is applied when generating the string representation.

See also:  - setStringValue:, - doubleValue, - floatValue, - intValue, - setFloatingPointFormat:left:right: (Cell)

NS_DEV_DOCFOR:objc_method:[SliderCell-title];,title

- (const char *)title

Returns the string used as the SliderCell's background title.  The title is drawn over the SliderCell's background.  Returns self.

See also:  - setTitle:

NS_DEV_DOCFOR:objc_method:[SliderCell-titleCell];,titleCell

- titleCell

Returns the TextFieldCell used to draw the SliderCell.  If the SliderCell doesn't have a title, a new TextFieldCell is created and returned.  This doesn't result in a title getting set.

See also:  - setTitleCell:

NS_DEV_DOCFOR:objc_method:[SliderCell-titleColor];,titleColor

- (NXColor)titleColor

Returns the color used to draw the SliderCell's background title.  The default is to draw in a gray level of 0.0 (NX_BLACK).  Returns self.

See also:  - setTitleColor:, - titleGray

NS_DEV_DOCFOR:objc_method:[SliderCell-titleFont];,titleFont

- titleFont

Returns the Font used to draw the SliderCell's title.  The default font is the default system font as set by the user (with the Preferences application), and its size is 12.0 point.

See also:  - setTitleFont:

NS_DEV_DOCFOR:objc_method:[SliderCell-titleGray];,titleGray

- (float)titleGray

Returns the gray value used to draw the SliderCell's background title.  The default gray level is 0.0 (NX_BLACK).  Returns self.

See also:  - setTitleGray:, - titleColor

NS_DEV_DOCFOR:objc_method:[SliderCell-trackMouse:inRect:ofView:];,trackMouse:inRect:ofView:

- (BOOL)trackMouse:(NXEvent *)theEvent
inRect:(const NXRect *)cellFrame
ofView:controlView

Tracks the mouse until it goes up or until it goes outside the cellFrame.  If cellFrame is NULL, then it tracks until the mouse goes up.  Since SliderCell responds YES to prefersTrackingUntilMouseUp, this method will be invoked with a NULL cellFrame.  Returns  YES if the mouse goes up, NO otherwise.

If the SliderCell is continuous, then the action will be continuously sent to the target as the mouse is dragged.  If cellFrame isn't the same cellFrame that was passed to the last drawSelf:inView:, then this method doesn't track.

See also:  - startTrackingAt:inView:, - continueTracking:at:inView:, - stopTracking:at:inView:mouseIsUp:, - setContinuous:

NS_DEV_DOCFOR:objc_method:[SliderCell-write:];,write:

- write:(NXTypedStream *)stream

Writes the receiving SliderCell to the typed stream stream.  Returns self.

See also:  - read: